# Xiaozhi AI 开放应用平台 # 顶层架构与 AI Coding Master Plan > Version: V1.0 > Date: 2026-08-30 > Purpose: 作为 Xiaozhi AI 硬件端、Server 端、小程序端以及未来开发者开放平台的最高层架构设计与 AI Coding 总体指导文档。 --- # 1. 项目最终目标 将现有 Xiaozhi AI 从： ```text AI 对话硬件 ``` 逐步升级为： ```text AI Application Terminal ``` 最终形态类似： ```text 手机 └── 可以安装多个 App └── 每个 App 包含多个 Task └── 每个 Task 包含多个 Step └── Step 调用底层能力 ``` 但是 Xiaozhi 与手机的核心区别是： ```text 手机： 用户主动选择 App → 主动操作 Xiaozhi： 家长配置 → 系统调度 → Xiaozhi 主动执行 → 儿童参与 ``` 因此 Xiaozhi 最终不是单纯的聊天机器人，而是： > **一个可以承载多个 AI App，并根据家长配置主动执行 Task，同时持续记录、评估和分析儿童行为的 AI 终端平台。** --- # 2. 最终产品形态 最终整个系统由： ```text Xiaozhi Device │ │ Xiaozhi Server │ ├── App Platform ├── Task Platform ├── Assessment Platform ├── User Data Platform ├── Developer Platform ├── Subscription Platform └── Parent Platform ``` 组成。 用户关系： ```text 平台 │ ├── App A │ ├── Task 1 │ ├── Task 2 │ └── Task 3 │ ├── App B │ ├── Task 1 │ └── Task 2 │ └── App C └── ... ``` 一个孩子可以订阅多个 App。 但是： ```text 同一时间 只能运行一个 App / Task Runtime ``` 因此不要求 Xiaozhi 硬件同时运行多个复杂应用。 --- # 3. 核心架构原则 整个系统必须坚持以下原则。 ## 3.1 App 是业务能力的容器 App 不应该等同于硬件功能。 例如： ```text 英语学习 App 回忆录 App 益智游戏 App AI 主持人 App ``` 都是逻辑应用。 --- ## 3.2 Task 是系统真正执行的基本业务单位 系统最终执行的是： ```text Task ``` 而不是： ```text Scenario ``` 例如： ```text 英语 App ├── 英语跟读 10 次 ├── 单词复习 └── 英语听力 ``` 其中： ```text 英语跟读 10 次 ``` 就是一个 Task。 --- # 4. Scenario / Interaction Mode 的最终定义 本项目中不再把 Scenario 理解为： ```text 业务场景 ``` 而定义为： > **Device Interaction Mode** 即： > Xiaozhi 在执行 Task 时，应该以什么方式与用户交互。 例如： ```text CHAT PLAY_AUDIO REPEAT FOLLOW_READ QUESTION_ANSWER TRANSLATION CALCULATION MEMORY GAME SILENT ``` 因此： ```text Task ↓ 指定 Interaction Mode ↓ Device Runtime ↓ 以对应方式执行 ``` 例如： ```text Task： 听英语复读机 10 遍 interactionMode： PLAY_AUDIO steps： 播放 → 等待 → 播放 → 等待 ... ``` 不需要额外建立： ```text Scenario ↓ Task ``` 这样的业务层级。 --- # 5. Task 是核心执行抽象 统一模型： ```text App └── Task └── Step └── Action / Skill ``` 例如： ```text English App └── English Repeat 10 Times ├── Play Audio ├── Wait ├── Record ├── Evaluate └── Repeat ``` --- # 6. Step 是真正的执行单元 Task 负责： ```text 做什么 ``` Step 负责： ```text 具体怎么一步一步做 ``` 例如： ```text Task： 英语跟读 Step 1： 播放标准音频 Step 2： 等待用户说话 Step 3： 录音 Step 4： ASR Step 5： 比较 Step 6： 评分 Step 7： 反馈 Step 8： 进入下一句 ``` --- # 7. Skill / Atomic Capability Step 不直接操作硬件。 Step 调用： ```text Skill ``` 例如： ```text play_audio record_audio listen speak wait count asr evaluate display led button ``` 最终： ```text Task ↓ Step ↓ Skill ↓ Device Capability ``` --- # 8. Device 与 Server 的职责边界 ## Device 负责： ```text 执行 播放 录音 采集 缓存 通信 基础状态 ``` --- ## Server 负责： ```text 调度 Task App 用户 数据 ASR AI 评估 分析 长期趋势 ``` --- # 9. App 不应该成为硬件固件 未来新增 App： ```text 下载配置 下载资源 ``` 而不是： ```text 修改 C++ 固件 重新 OTA ``` 理想情况下： ```text 新增 App ↓ App Manifest Task Definition Step Definition Resource Assessment Definition ↓ Server ↓ Device Sync ``` 即可运行。 --- # 10. App Manifest 每一个 App 都有： ```text app.json ``` 定义： ```text appId name version developerId description icon tasks resources permissions assessment ``` --- # 11. Task Definition Task 定义： ```text taskId name description version steps parameters interactionMode assessment resources ``` 例如： ```json { "taskId": "english_repeat_10", "interactionMode": "PLAY_AUDIO", "parameters": { "repeatCount": 10 } } ``` --- # 12. Resource App 可以携带： ```text MP3 WAV 图片 JSON 文本 配置 模型参数 ``` 这些属于： ```text Application Resource ``` 而不是固件。 --- # 13. OTA 与 App 更新必须彻底区分 ## OTA 用于： ```text Device Firmware ``` 例如： ```text 底层驱动 通信协议 音频驱动 系统 Runtime ``` --- ## App Sync 用于： ```text App Task Config Resource Audio ``` 例如： ```text 新增英语 App ``` 只需要： ```text Sync App ``` 无需 OTA。 --- # 14. SD Card 的定位 16GB SD Card 主要用于： ```text App Resources Audio Resources Cache Offline Tasks Pending Upload Audio Temporary Files ``` 例如： ```text /sdcard/ apps/ resources/ audio/ cache/ recordings/ pending/ ``` --- # 15. Server Task Runtime Server 必须建立统一： ```text Task Runtime ``` 负责： ```text 创建 TaskInstance 启动 Task 推进 Step 等待 Device 处理 Event 判断 Step 完成 进入下一 Step 结束 Task ``` --- # 16. Task Instance 不要直接修改 Task Definition。 每一次实际执行： ```text Task ↓ TaskInstance ``` 例如： ```text Task： 英语跟读 10 次 TaskInstance： 2026-08-30 19:30 ``` 保存： ```text startTime endTime status currentStep result ``` --- # 17. Scheduler 家长通过小程序配置： ```text 每天 19:30 英语学习 ``` Server： ```text Schedule ↓ Scheduler ↓ TaskInstance ↓ Device ``` 因此： > 家长配置的是“什么时候做什么 Task”，不是直接控制硬件。 --- # 18. Plan 进一步允许： ```text Plan ``` 例如： ```text 每日学习计划 ``` 包含： ```text 19:30 英语跟读 19:45 口算 19:55 记忆游戏 ``` 最终： ```text Plan ↓ Schedule ↓ TaskInstance ``` --- # 19. Device Runtime Device 只需要理解标准协议： ```text APP_SYNC TASK_START STEP_START SKILL_EXECUTE TASK_PAUSE TASK_RESUME TASK_STOP ``` 以及向 Server 上报： ```text TASK_STARTED STEP_STARTED STEP_COMPLETED AUDIO_PLAYED SPEECH_STARTED SPEECH_STOPPED TASK_COMPLETED ``` --- # 20. Interaction Runtime Device Runtime 内部增加： ```text Interaction Runtime ``` 根据： ```text interactionMode ``` 选择交互方式。 例如： ```text PLAY_AUDIO → Audio Player FOLLOW_READ → Audio Player → Recorder → VAD CHAT → ASR → LLM → TTS TRANSLATION → ASR → Translation → TTS ``` --- # 21. Chat 不再是唯一 Runtime 现有 Xiaozhi 很可能： ```text Audio ↓ ASR ↓ LLM ↓ TTS ``` 这种架构。 必须升级成： ```text Task Runtime ↓ Interaction Runtime ↓ ┌────────┬────────┬────────┬────────┐ Chat Audio Repeat Game ... ``` Chat 只是其中一种能力。 --- # 22. Server Audio Architecture Server 保存： ```text Original Audio ``` 而不是只保存： ```text ASR Text ``` 结构： ```text AudioSession └── AudioSegment ├── Original Audio ├── ASR ├── Voice Feature └── Assessment ``` --- # 23. ASR 统一 ASR Service： ```text Audio ↓ ASR ↓ Transcript ``` 保存： ```text text confidence word timing word confidence ``` --- # 24. Voice Analysis 统一提取： ```text speechDuration pauseCount pauseDuration speechRate responseLatency volume pitch energy prosody ``` --- # 25. Task Assessment 不同 Task 使用不同评估策略。 例如： ```text 英语跟读 → pronunciation → fluency → accuracy 数字倒背 → sequenceAccuracy → memoryAccuracy → responseTime 口算 → accuracy → responseTime → difficulty 成语接龙 → correctness → responseTime → continuity ``` --- # 26. Metric System 所有结果最终统一为： ```text Metric ``` 例如： ```text accuracy response_time pause_count speech_rate pronunciation fluency completion participation engagement ``` 新 App 可以注册新的 Metric。 --- # 27. Behavioral Analysis Server 建立： ```text User Baseline ``` 通过： ```text 7 Days 30 Days 90 Days ``` 形成动态基线。 然后比较： ```text Today vs Baseline ``` --- # 28. Emotion Analysis 系统可以提供： ```text Emotion Signal ``` 但必须定义为： > **基于语音、语言和行为数据的情绪表现信号。** 不能直接定义为： ```text 心理疾病诊断 ``` 输出： ```text state confidence trend ``` --- # 29. Engagement 建立： ```text Engagement Score ``` 综合： ```text 响应 完成 主动性 持续性 互动 ``` 形成： ```text 0 ~ 100 ``` --- # 30. Parent Dashboard 家长最终看到： ```text 今日任务 完成情况 Task Score 能力指标 参与度 趋势 ``` 而不是复杂技术指标。 --- # 31. Long-term Profile 系统持续形成： ```text User Profile ``` 包括： ```text Learning Memory Speech Task Performance Participation Behavior Trend Preference ``` 所有 Profile 都应该来自： ```text Event ↓ Metric ↓ Aggregation ``` 而不是手工维护。 --- # 32. Developer Platform 最终开放： ```text Developer ↓ App ↓ Task ↓ Step ↓ Skill ↓ Assessment ``` 开发者不应该直接修改 Device Firmware。 --- # 33. Developer Sandbox 提供： ```text App SDK Task SDK Assessment SDK Resource SDK API Simulator ``` 开发者可以在 PC 上模拟： ```text Xiaozhi Device ``` 测试 Task。 --- # 34. App Store 最终平台形成： ```text App Store ``` 用户可以： ```text 浏览 App 查看介绍 试用 订阅 安装 评价 ``` 例如： ```text 英语学习 数学训练 记忆训练 成语游戏 AI 主持人 回忆录 故事 ``` --- # 35. Subscription 订阅关系： ```text User ↓ Subscription ↓ App ``` 而不是： ```text User ↓ Firmware ``` --- # 36. Developer Revenue 平台负责： ```text 订单 支付 订阅 退款 结算 分成 ``` 开发者获得： ```text Revenue Share ``` --- # 37. Permission Architecture 必须建立： ```text User Child Parent Developer App ``` 之间的权限体系。 尤其是儿童数据。 开发者： ```text 默认不能读取其他 App 数据 ``` 家长： ```text 可以查看孩子数据 ``` 平台： ```text 负责权限控制 ``` --- # 38. Privacy 儿童语音必须重点保护。 建立： ```text Consent Encryption Access Control Audit Log Retention Policy Data Deletion ``` --- # 39. 数据核心链路 最终统一成： ```text App ↓ Task ↓ TaskInstance ↓ StepInstance ↓ Device Event ↓ Audio ↓ ASR ↓ Voice Feature ↓ Assessment ↓ Metric ↓ Aggregation ↓ Profile ↓ Report ``` 这是整个系统最重要的数据链路。 --- # 40. Event-Driven Architecture 核心状态尽量由 Event 驱动。 例如： ```text TaskStarted StepStarted AudioPlayed SpeechStarted SpeechStopped ASRCompleted AssessmentCompleted StepCompleted TaskCompleted ``` Event 成为系统的重要事实来源。 --- # 41. 异步分析 实时链路： ```text Device ↓ Server ↓ Task Runtime ↓ 实时反馈 ``` 异步链路： ```text Audio ↓ Queue ↓ ASR ↓ Voice Analysis ↓ Assessment ↓ Aggregation ↓ Report ``` 复杂 AI 分析不能阻塞 Task Runtime。 --- # 42. 离线能力 Device 网络断开时： ```text Task ↓ Local Cache ↓ 执行 ↓ Recording ↓ SD Card ↓ 网络恢复 ↓ Sync ``` 因此： > Server 是中心控制器，但 Device 必须具备一定程度的 Offline Runtime。 --- # 43. 版本管理 所有这些对象必须版本化： ```text Firmware App Task Step Assessment Model Resource ``` 例如： ```text App v1.2 Task v3 Assessment v2 Model v5 ``` 历史数据必须能够追溯到具体版本。 --- # 44. 不覆盖历史结果 例如： ```text Pronunciation Model v1 Score = 82 ``` 以后： ```text Pronunciation Model v2 Score = 87 ``` 两个结果都保留。 --- # 45. 推荐的数据库关系 核心： ```text User └── Child Child ├── Subscription ├── Plan ├── Schedule └── TaskInstance App └── Task └── TaskStep TaskInstance └── TaskStepInstance ├── DeviceEvent ├── AudioSegment │ ├── ASR │ └── VoiceFeature └── Assessment └── Metric ``` --- # 46. 第一阶段开发目标 不要一开始开发完整平台。 首先建立最小闭环： ```text 家长 ↓ 配置 Task ↓ Server Scheduler ↓ TaskInstance ↓ Xiaozhi ↓ 执行 ↓ 录音 ↓ Server ↓ ASR ↓ Assessment ↓ 家长查看结果 ``` 必须完整跑通。 --- # 47. MVP Task 第一阶段只实现三个 Task： ## Task A：英语复读 ```text 播放 ↓ 等待 ↓ 播放 ↓ ... ``` --- ## Task B：英语跟读 ```text 播放标准音频 ↓ 录音 ↓ ASR ↓ 准确率 ``` --- ## Task C：口算 ```text 播放问题 ↓ 等待回答 ↓ ASR ↓ 答案解析 ↓ 正确率 ``` --- # 48. 第二阶段 增加： ```text 数字倒背 成语接龙 简单记忆游戏 ``` 并统一： ```text Task Engine Step Engine Assessment Engine ``` --- # 49. 第三阶段 加入： ```text Voice Feature ``` 实现： ```text Pause Speech Rate Response Latency Volume Pitch ``` --- # 50. 第四阶段 加入： ```text Baseline Behavior Engagement Participation ``` 实现： ```text Today 7 Days 30 Days ``` 趋势。 --- # 51. 第五阶段 建立： ```text Emotion Signal ``` 进行实验性分析。 要求： ```text 模型版本化 置信度 趋势 人工验证 ``` 不允许直接做医疗诊断。 --- # 52. 第六阶段 开放： ```text App Manifest Task DSL Assessment SDK Developer API ``` 实现第三方 App。 --- # 53. 第七阶段 建立： ```text App Store Subscription Payment Revenue Share Developer Console ``` --- # 54. 第八阶段 建立： ```text Parent AI Assistant ``` 家长可以询问： ```text 孩子最近学习怎么样？ 哪个 App 最喜欢？ 英语最近有没有进步？ 最近参与度有没有下降？ 过去一个月有什么明显变化？ ``` AI 从： ```text Metrics Assessment Trend Profile ``` 中生成解释。 --- # 55. AI Coding 总体实施顺序 AI Coding 不允许一次性重写整个项目。 必须： ```text Phase 0 代码审计 Phase 1 建立核心 Domain Model Phase 2 Task Runtime Phase 3 Device Runtime Phase 4 App / Resource Sync Phase 5 Audio / ASR Phase 6 Assessment Phase 7 Parent / Schedule Phase 8 Behavior / Metrics Phase 9 Developer Platform Phase 10 Subscription / Marketplace ``` 每个 Phase： ```text 分析 ↓ 设计 ↓ 实现 ↓ 测试 ↓ 回归 ↓ 提交 ``` --- # 56. AI Coding 第一原则 AI 编程 Agent 必须： > **优先理解现有代码，再修改代码。** 禁止： ```text 没有阅读代码 ↓ 直接重构 ``` 必须： ```text Repository Audit ↓ Architecture Mapping ↓ Dependency Analysis ↓ Minimal Change ``` --- # 57. 不允许无理由重写现有功能 现有 Xiaozhi 的： ```text Audio ASR TTS LLM MQTT / WebSocket Device Communication ``` 能够复用的必须复用。 新架构应该： ```text 包裹现有能力 ``` 而不是： ```text 全部推倒重来 ``` --- # 58. 新旧系统迁移策略 旧系统： ```text Conversation ``` 保留。 增加： ```text Task Runtime ``` 最终： ```text Task Runtime ├── Chat Task ├── Repeat Task ├── Follow Read Task ├── Translation Task └── Game Task ``` 因此： > Chat 最终只是 Task Runtime 的一种 Task，而不是整个系统的核心。 --- # 59. API 设计原则 所有 API 必须围绕： ```text App Task TaskInstance StepInstance Event Audio Assessment Metric ``` 设计。 避免大量： ```text /english/xxx /math/xxx /game/xxx ``` 这种 App-specific API。 --- # 60. Task DSL 原则 未来开发者应该能够通过： ```text JSON / YAML / SDK ``` 定义 Task。 例如： ```text Task ├── parameters ├── steps │ ├── action │ ├── condition │ ├── wait │ ├── loop │ └── branch └── assessment ``` 这样： > 新增 Task 尽量不需要修改核心 Runtime。 --- # 61. Runtime 的稳定边界 必须建立稳定的： ```text Task Runtime API Skill API Device API Assessment API ``` 未来 App 越多： ```text Runtime 不变 App 增加 Task 增加 ``` 这是开放平台成立的关键。 --- # 62. 最终架构图 ```text Xiaozhi Platform │ ┌──────────────────┼──────────────────┐ │ │ │ Parent Developer Device │ │ │ ↓ ↓ ↓ Plan App Store Device Runtime │ │ │ Schedule App Interaction │ │ │ └──────────────→ Task ←───────────────┘ │ Step │ Skill │ Device Capability │ ↓ Audio / Event │ ↓ Server Pipeline │ ┌──────────────────┼─────────────────┐ ↓ ↓ ↓ ASR Voice Analysis Assessment │ │ │ └──────────────────┼─────────────────┘ ↓ Metric ↓ Aggregation ↓ User Profile ↓ Parent Report ``` --- # 63. 最终平台的核心抽象 整个项目最终只需要牢牢抓住以下 8 个核心概念： ```text App Task Step Skill Interaction Mode Event Assessment Metric ``` 它们之间： ```text App ↓ Task ↓ Step ↓ Skill ↓ Device ``` 执行过程中产生： ```text Event ↓ Audio ↓ Assessment ↓ Metric ``` --- # 64. 最终产品逻辑 因此最终 Xiaozhi 的逻辑不是： ```text 用户 ↓ 说话 ↓ AI 回复 ``` 而是： ```text 家长 ↓ 订阅 App ↓ 配置 Plan ↓ 配置 Schedule ↓ Server ↓ Task ↓ Xiaozhi ↓ 执行 Step ↓ 采集 Audio / Event ↓ Server 分析 ↓ Assessment ↓ Metric ↓ 长期 Profile ↓ 家长 ``` --- # 65. 项目的最终战略目标 第一阶段： ```text 让 Xiaozhi 能执行 Task ``` 第二阶段： ```text 让 Xiaozhi 能记录 Task ``` 第三阶段： ```text 让 Xiaozhi 能评估 Task ``` 第四阶段： ```text 让 Xiaozhi 能理解长期变化 ``` 第五阶段： ```text 让任何开发者都能创建 Task / App ``` 第六阶段： ```text 让 App 可以订阅和商业化 ``` 最终： > **Xiaozhi Device 成为终端，Task Runtime 成为执行引擎，Server 成为 AI 数据与调度中枢，App Store 成为生态入口。** --- # 66. 给 AI Coding Agent 的最高级指令 后续将本 Plan 提供给 Cursor / Codex 等 Coding Agent 时，应遵守： ```text 你正在参与的是 Xiaozhi AI 从“AI 对话设备” 向“AI Application Terminal Platform”的架构升级。 不要把 Xiaozhi 设计成只有 Chat 的机器人。 系统必须支持： App Task Step Skill Interaction Mode Task Instance Event Audio ASR Assessment Metric Schedule User Profile Task 是系统核心业务执行单位。 Interaction Mode 是设备交互方式， 不是业务层级。 App 是 Task 的业务容器。 Step 是 Task 的执行步骤。 Skill 是底层原子能力。 Device 负责执行和采集。 Server 负责调度、理解、分析、评估和长期数据管理。 新增 App / Task / Audio Resource 尽量通过配置和资源同步实现， 不应该依赖 Firmware OTA。 必须保持旧 Chat 能力继续工作。 所有新架构必须尽可能兼容和复用现有代码。 禁止在未完成代码审计之前大规模重构。 每个 Phase 必须： 1. 分析现有代码 2. 明确修改范围 3. 给出架构方案 4. 实施最小必要修改 5. 编写测试 6. 执行测试 7. 验证旧功能没有回归 8. 输出修改总结 不要一次性实现整个系统。 必须按照 Phase 逐步演进。 优先建立稳定的 Domain Model 和 Runtime Boundary。 未来第三方开发者应该能够在不修改 Xiaozhi 核心 Runtime 的情况下创建新的 App 和 Task。 最终目标是： “核心 Runtime 稳定，App / Task / Resource / Assessment 可无限扩展。” ``` --- # 67. Master Plan 的执行方式 以后所有 Coding Plan 都应该从本 Master Plan 派生。 结构： ```text Master Plan │ ├── Device Plan │ ├── Server Plan │ ├── Mini Program Plan │ ├── Developer Platform Plan │ ├── Assessment Plan │ └── Marketplace Plan ``` 然后再进一步： ```text Architecture Plan ↓ Module Plan ↓ Implementation Plan ↓ Coding Task ↓ Code ↓ Test ``` --- # 68. 最终判断标准 以后任何一个新需求，都先问： ```text 这是 App？ 是 Task？ 是 Step？ 是 Skill？ 是 Interaction Mode？ 是 Event？ 是 Assessment？ 还是 Metric？ ``` 如果一个新需求无法归入这些核心抽象： > 不要立即写代码。 先重新审视架构。 这套原则将决定 Xiaozhi 最终能不能从一个产品，真正演化成一个开放平台。